{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example Notebook to demonstrate the simplicity of saving data in QKIT"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### First import the QKIT store module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import qkit\n",
    "from qkit.storage import store"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... some imports to create some random data ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## for random data\n",
    "from numpy.random import rand\n",
    "from numpy import linspace,arange\n",
    "import time\n",
    "## number of points\n",
    "nop = 101"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a data file object\n",
    "The file name will be ** prepended by a unique 6 character identifier (UUID) ** \n",
    "and the file saved in a standard path below\n",
    "qkit.cfg['datadir']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "h5d = store.Data(name='NewFancyData',mode = \"a\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "** h5d ** is now an empty hdf5 file, holding only some qkit structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### How to get the file path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(h5d.get_filepath())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Now use qviewkit to open and view the file\n",
    "##### Hint: in a fully started qkit environment (qkit.start()) This can be done by qkit.fid.view(\"UUID\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Comment added to the basic hdf folder\n",
    "\n",
    "options\n",
    " * comment (mandatory)\n",
    " * folder='data' | 'analysis' (optional, default is \"data\") "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "h5d.add_comment(\"New data has been created ....\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Now we get to the important stuff: \n",
    "\n",
    " * first we have to create the objects which are later used to store the data\n",
    " * then we can add data "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### A coordinate is a 1-dim vector with bias values, e.g. set current, frequencies, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add_coordinate()    <- for measurement boundaries/steps\n",
    "# options: name (mandatory)\n",
    "#        : unit = \"\" (optional, default is \"a.u.\")\n",
    "#        : comment = \"\" (optional, default is \"\")\n",
    "#        : folder='data' | 'analysis' (optional, default is \"data\") \n",
    "f_co = h5d.add_coordinate('frequency', unit = \"Hz\",   comment = \"VNA frequency scan\")\n",
    "I_co = h5d.add_coordinate('current',   unit = \"A\",    comment = \"magnetic field current\")\n",
    "P_co = h5d.add_coordinate('power',     unit = \"dBm\",  comment = \"microwave power\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### A value_vector ie is a 1-dim vector measured values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add_value_vector()    <- for measurement data\n",
    "# options: name (mandatory)\n",
    "#        : x = X  (optional) coordinate vector in x direction, default: None\n",
    "#        : unit = \"\" (optional, default is \"a.u.\")\n",
    "#        : comment = \"\" (optional, default is \"\")\n",
    "#        : folder='data' | 'analysis' (optional, default is \"data\") \n",
    "\n",
    "T_vec = h5d.add_value_vector('temperature', x = None, \n",
    "                             unit = \"K\", comment = \"save temperature values\") \n",
    "Tc_vec = h5d.add_value_vector('critical_temperature', x = I_co, \n",
    "                              unit = \"K\", folder='analysis' ,comment = \"save temperature values\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### A value_matrix is a 2-dim tuple with two cooardinates with measurement values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add_value_matrix()    <- for measurement data\n",
    "# convention: the last coordiante should be the one with the fastest changes:\n",
    "#             e.g.  for a VNA scan x= magnetic field y= transmission frequency\n",
    "# \n",
    "# options: name (mandatory)\n",
    "#        : x = X  (optional) coordinate vector in x direction, default: None\n",
    "#        : y = Y  (mandatory) coordinate vector in y direction / fastest changes\n",
    "#        : unit = \"\" (optional, default is \"a.u.\")\n",
    "#        : comment = \"\" (optional, default is \"\")\n",
    "#        : folder='data' | 'analysis' (optional, default is \"data\") \n",
    "\n",
    "amp_mx = h5d.add_value_matrix('amplitude', x = I_co , y = f_co, \n",
    "                              unit = \"V\", comment = \"magic data\")\n",
    "pha_mx = h5d.add_value_matrix('phase',     x = I_co , y = f_co, \n",
    "                              unit = \"rad\", comment = \"more magic data!\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### A value_box is a 3-dim tuple with three cooardinates with measurement values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add_value_box()    <- for measurement data\n",
    "# options: name (mandatory)\n",
    "#        : x = X  (optional) coordinate vector in x direction, default: None\n",
    "#        : y = Y  (optional) coordinate vector in y direction\n",
    "#        : z = Z  (mandatory) coordinate vector in y direction /  fastest changes\n",
    "#        : unit = \"\" (optional, default is \"a.u.\")\n",
    "#        : comment = \"\" (optional, default is \"\")\n",
    "#        : folder='data' | 'analysis' (optional, default is \"data\") \n",
    "\n",
    "amp_bx = h5d.add_value_box('amplitude', x = I_co , y = f_co, z= P_co, \n",
    "                           unit = \"V\", comment = \"magic data\")\n",
    "pha_bx = h5d.add_value_box('phase',     x = I_co , y = f_co, z= P_co, \n",
    "                           unit = \"rad\", comment = \"more magic data!\")\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### For free text, like settings or commments there is a special dataset which can be appended to add data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#string array \n",
    "#add_textlist()\n",
    "#options: name (mandatory)\n",
    "#       : comment = \"\"   (optional)\n",
    "#       : folder=\"data\"  (optional)\n",
    "# use the append method to add the text\n",
    "settings = h5d.add_textlist(\"settings\",comment = \"my settings\")\n",
    "settings.append(u\"vnapower = 10dBm\")\n",
    "settings.append(u\"fridge attenuation=50db\\n data jumps like Van Halen.\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### If one want to plot a arbitrary dataset vs another arbitrary dataset use a view"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "### Add a view on Data:\n",
    "\n",
    "TvsTc_view = h5d.add_view(\"f_vs_I\", x = f_co, y = I_co)\n",
    "\n",
    "TvsTc_view.add(x=T_vec,y=Tc_vec)\n",
    "\n",
    "Laspect_view = h5d.add_view(\"locked_aspect\", x = f_co, y = f_co, \n",
    "                            view_params={'aspect':1.0, 'bgcolor':(100,200,100)})\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Finally add some data to the file\n",
    "There are two functions to do so:\n",
    "  * append(data)  <- this is the most frequently used method, it does what it says.\n",
    "  * add(data)     <- this is used to set a dataset of lenght N to the data with length N"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "lets make an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# now we add the coordinate data to the file\n",
    "fs = linspace(1e9,5e9,nop)\n",
    "Is = linspace(0e-3,10e-3,nop)\n",
    "\n",
    "\n",
    "f_co.add(fs)\n",
    "I_co.add(Is)\n",
    "\n",
    "for i in arange(nop):\n",
    "    #time.sleep(10)\n",
    "    amp = rand(nop)\n",
    "    pha = rand(nop)\n",
    "    amp_mx.append(amp)\n",
    "    pha_mx.append(pha)\n",
    "    T_vec.append(float(rand(1)))\n",
    "    Tc_vec.append(float(rand(1)))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Close the file at the end"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "h5d.close_file()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
